/* File: GpsAPI.h
 * --------------
 * This file specifies the API defined by the GpsAPI.lib.  This API is designed to be used to
 * communicate data and state values between upper layer applications and the Centrality GPS
 * baseband.
 *
 * Author: Howard Shen - Centrality Communications, MTS.
 * 
 * Centrality Communications, Copyright 2003.  All rights reserved.
 */

#ifndef _GPSAPI_H_   
#define _GPSAPI_H_

#ifdef __cplusplus
extern "C" {
#endif

//#include "struct.h"
#include "GpsDataTypes.h"



/* Function: StartGpsApi
 * ---------------------
 * This function must be called first in any application which attemps to use the GPS API.  It
 * opens GPS com port. All API functions are based on the handle of this com port. Before
 * a call to this function, no API functions will work.
 */
bool StartGpsApi();

/* Function: StopGpsApi
 * ---------------------
 * This function must be called first before application exit.
 */
bool StopGpsApi();


// Satellite Data Functions
// ------------------------

/* Function: GetAlmanac
 * --------------------
 * This function completes a struct ALMANAC, passed in by address, for the satellite with the 
 * given svid.  The function returns TRUE if successful.
 */
bool GetAlmanac(int svid, ALMANAC* almanac);


/* Function: GetEphemeris
 * ----------------------
 * This function completes a struct EPHEMERIS, passed in by address, for the satellite with
 * the given svid.  The function returns TRUE if sucessful.
 */
bool GetEphemeris(int svid, EPHEMERIS* ephemeris);


/* Function: GetSatelliteCN0Ratio
 * ------------------------------
 * This function returns the ratio of carrier and noise of the specified satellite.
 */
unsigned char GetSatelliteCN0Ratio(int svid);


/* Function: GetSatelliteAzimuth
 * ------------------------------
 * This function returns the azimuth of the specified satellite.
 */
int GetSatelliteAzimuth(int svid);


/* Function: GetSatelliteElevation
 * ------------------------------
 * This function returns the elevation of the specified satellite (in degrees).
 */
int GetSatelliteElevation(int svid);


/* Function: GetSatelliteECEF
 * --------------------------
 * This function completes a struct ECEFPOSITION, passed in by address, for the satellite
 * with the specified svid.  The function returns TRUE if successful.
 */
bool GetSatelliteECEF(int svid, ECEFPOSITION* ecefpos);


/* Function: GetChannelSat
 * --------------------------
 * This function returns the satellite PRN of the corresponding channel
 */
int GetChannelSat(short channel);//By Qiu Zongde 04/08/03


/* Function: GetChannelState
 * -----------------------
 * This function returns the tracking status of the satellite with the specified channel.
 * The format of the returned char willbe as follows:
 * 	Bit 0: bit sync has been obtained
 * 	Bit 1: fine track status has been obtained
 * 	Bit 2: acquisition has been secure
 * 	Bit 3: trickle power flag is being used
 * 	Bit 4: bit deduction is being used
 */
unsigned short GetChannelState(short channel);//By Qiu Zongde 04/08/03


/* Function: GetChannelPower
 * --------------------------
 * This function returns the signal power of the corresponding channel
 */
unsigned long GetChannelPower(short channel);//By Qiu Zongde 04/08/03


/* Function: GetIonoData
 * ------------------------------
 * This function completes a struct IONOPARAM, passed in by address, for the satellite with
 * the given svid.  The function returns TRUE if successful.
 */
bool GetIonoData(IONOPARAM* ionoparam);


/* Function: GetPosition
 * ---------------------
 * This function completes a struct LAAPOSITION, passed in by address, for the satellite
 * with the specified svid.  The function returns TRUE if successful.
 */
bool GetPosition(LLAPOSITION* position);


// DOP functions
// -----------------------

/* Function: GetGDOP
 * -----------------
 * This function returns the geometric dilution of precistion of the receiver.
 */
double GetGDOP();


/* Function: GetPDOP
 * -----------------
 * This function returns the positional dilution of precistion of the receiver.
 */
double GetPDOP();


/* Function: GetHDOP
 * -----------------
 * This function returns the horizontal dilution of precistion of the receiver.
 */
double GetHDOP();


/* Function: GetVDOP
 * -----------------
 * This function returns the vertical dilution of precistion of the receiver.
 */
double GetVDOP();


/* Function: GetTDOP
 * -----------------
 * This function returns the dilution of precistion of time of the receiver.
 */
double GetTDOP();


/* Function: GetCurrentUTC
 * -------------------------
 * This function completes a struct UTCTIME, passed in by address.  The function 
 * returns TRUE if successful.  If this is called prior to the GPS system's successful
 * calculation of GPS UTC, the system time (e.g. the time of the WinCE system) will
 * be returned.  Once the actual GPS UTC time is determined, this function will
 * return the GPS UTC time.  Because this function is suseptible to system latency,
 * it is only accurate to the nearest second.
 */
bool GetCurrentUTC(UTCTIME* time);


/* Function: GetUsedSatNumber
 * -------------------------
 * This function return the number of the satellites used in PVT
 */ 
int GetUsedSatNumber();


/* Function: GetGroundSpeed
 * ------------------------
 * This function returns the ground speed of the receiver in knots.
 */
double GetGroundSpeed();


/* Function: GetMaskParams
 * -----------------------
 * This function gets the masking parameters including DOP, Elevation, and Power masks
 * and completes the maskparam passed in by address.
 */
bool GetMaskParams(MaskParam* maskparam);


/* Function: GetCrystalOffset
 * --------------------
 * This function returns the receiver's crystal offset in Hz.
 */
double GetCrystalOffset();


/* Function: GetNMEAType
 * ----------------------
 * This function gets the output characteristics of the GPS receiver NMEA messages.  This 
 * function will return TRUE upon success.
 */
bool GetNMEAType(NMEAParam *nmea);


/* Function: GetTemperature
 * ----------------------
 * This function gets the temperature from the temperature sensor. 
 */
double GetTemperature();


/* Function: GetSoftwareVer
 * ------------------------
 * This function returns the current version of the Centrality GPS software.
 */
char* GetSoftwareVer();


/* Function: GetReceiverStatus
 * ------------------------
 * This function returns the current current status of the GPS.
 */
unsigned long GetReceiverStatus();


/* Function: SetAlmanac
 * --------------------
 * This function sets the almanac data for a satellite. The function returns TRUE if successful.
 */
bool SetAlmanac(ALMANAC *newalmanac);


/* Function: SetEphemeris
 * ----------------------
 * This function sets the ephemeris data for a satellite.  This can be used
 * to expedite TTFF.
 */
bool SetEphemeris(EPHEMERIS* newephem);


/* Function: SetPosition
 * ---------------------
 * This function sets the position of the receiver in terms of latitude, longitude,
 * and altitude.  These values are passed in using an LAAPOSITION struct.  In order 
 * for these parameters to get used by the system, the user must set the "available" 
 * field to TRUE.  The function returns TRUE if successful.
 */
bool SetPosition(LLAPOSITION* position);


/* Function: SetReceiverUTC
 * -------------------------
 * This function sets the UTC time of the system using a UTCTIME struct.  When the
 * GPS system is started, it will use the system time as the assumed time.  After
 * the GPS UTC time is determined, this time will be used for further GPS calculations.
 * Calling this function after a position fix has been attained will only have teh effect
 * of changing the system (e.g. WinCE) time.  The GPS time will not be effected.  This
 * funtions returns TRUE if successful.
 */
bool SetReceiverUTC(UTCTIME* time);

   
/* Function: SetMaskParams
 * -----------------------
 * This function sets the masking parameters including DOP, Elevation, and Power masks
 * using a MaskParam struct.  In order for these parameters to get used by the system,
 * the user must set the "available" field to TRUE.  This function will return TRUE upon success.
 */
bool SetMasks(MaskParam* masks);


/* Function: SetNMEAType
 * ----------------------
 * This function sets the output characteristics of the GPS receiver NMEA messages using the 
 * NMEAPARAM structure.  The user must specify the frequency (in seconds per message) for each
 * NMEA message in the struct.  In order for these parameters to get used by the system, the 
 * user must set the "available" field to TRUE.  This function will return TRUE upon success.
 */
bool SetNMEAType(NMEAParam *nmea);


/* Function: GPSEnableWAAS
 * ---------------------
 * This function enable or disable the WAAS.  The function returns TRUE if successful.
 */
//bool GPSEnableWAAS(bool Enable);


/* Function: SetSBASType
 * ----------------------
 * This function set the SBAS type:
 * sbastype:
 * 0 -- NONE
 * 1 -- WAAS Auto Selection
 * 2 -- EGNOS Auto Selection
 * 3 -- ESTB Auto Selection
 * 4 -- MSAS Auto Selection
 * >4 -- SBAS SVID
 */
bool SetSBASType(int sbastype);

/* Function: SetChannelNumber
 * ---------------------
 * This function sets the channel number of hot/warm/cold start to GPS
 * The valid range to set is [1, 32]
 */
bool SetChannelNumber(int chnumber);

/* Function: GetChannelNumber
 * ---------------------
 * This function gets the channel number from GPS regarding the start type
 * iscoldstart:
 * true -- the channel number of cold start
 * flase -- the channel number of hot/warm start
 */
int GetChannelNumber(bool iscoldstart);

/* Function: SetStaticConstraint
 * ---------------------
 * This function enables the detection of stop/move status and apply it to the PVT result
 * If this function is enabled, if stop status is detected, the output position will fix
 * to a static position until the movement of the receiver is detected.
 * This function will return TRUE upon success.
 */
bool SetStaticConstraint(bool bConstraint);

/* Function: GPSHotStart
 * ---------------------
 * This function starts up the GPS baseband in Hot Start mode.  This function takes as its
 * only parameter a COM port which has been opened by the application where NMEA data is 
 * expected.  If NULL is passed in as the HANDLE, GPS will start, but no NMEA information
 * will be exported.  The Centrality GPS virtual COM port is COM7.  It is always possible to
 * retrieve GPS NMEA information through COM7.  The handle specified here is meant to be used for
 * ports other than COM7.  This function will return TRUE upon success.
 */
bool GPSHotStart();


/* Function: GPSWarmStart
 * ----------------------
 * This function starts up the GPS baseband in Warm Start mode.  This function takes as its
 * only parameter a COM port which has been opened by the application where NMEA data is 
 * expected.  If NULL is passed in as the HANDLE, GPS will start, but no NMEA information
 * will be exported.  The Centrality GPS virtual COM port is COM7.  It is always possible to
 * retrieve GPS NMEA information through COM7.  The handle specified here is meant to be used for
 * ports other than COM7.  This function will return TRUE upon success.
 */
bool GPSWarmStart();

/* Function: GPSColdStart
 * ----------------------
 * This function starts up the GPS baseband in Cold Start mode.  This function takes as its
 * only parameter a COM port which has been opened by the application where NMEA data is 
 * expected.  If NULL is passed in as the HANDLE, GPS will start, but no NMEA information
 * will be exported.  The Centrality GPS virtual COM port is COM7.  It is always possible to
 * retrieve GPS NMEA information through COM7.  The handle specified here is meant to be used for
 * ports other than COM7.  This function will return TRUE upon success.
 */
bool GPSColdStart();


/* Function: GPSFlexibleHotStart
 * ---------------------
 * This function is the same as hot start with the exception that it provide flexible control
 * to the frequency search range and first timeout time to switch satellites.
 */
bool GPSFlexibleHotStart(int SearchRange, int Timeout, int StartType);


/* Function: GPSShutdown
 * ---------------------
 * This function shuts down the GPS receiver.  The function returns TRUE if successful.
 */
bool GPSShutdown();


/* Function: GPSReset
 * ------------------
 * This function resets the GPS receiver.  Tracking will cease and restart with the default parameters.
 * This call is functionally equivalent to closing the COM port from a previous start (or calling 
 * GPSShutdown) and then calling GPSHotStart() from this API.  If failure occurs, NULL is returned.
 */
bool GPSReset();


/* Function: AllChSearchOneSV
 * --------------------------
 * This function sets the GPS baseband into a special mode where all channels are used to track one
 * specific satellite.  The function returns TRUE if successful.
 */
bool AllChSearchOneSV(int SV);


/* Function: CheckParameter
 * --------------------------
 * This function check the existance and validation of the parameters saved, return TRUE if exist
 * and valid, FALSE otherwise
 */
bool CheckParameter();


/* Function: RemoveParameter
 * --------------------------
 * This function remove the saved parameters or set the flag as invalid, return TRUE on success or
 * parameter does not exist, FALSE otherwise
 */
bool RemoveParameter();


/* Function: SaveParam
 * --------------------------
 * This function will save parameters into nandflash, return TRUE on success, FALSE otherwise
 */
bool SaveParam();

/* Function: GetGpsVersion
 * --------------------------
 * This function returns the GPS firmware verison. Bit15 to bit10 is major version, bit9 to bit0 is
 * minor version, bit31 to bit16 is reserved and should be 0
 */

/* Function: EnableTestParamSave
 * --------------------------
 * This function enables or disables test param file save
 */
bool EnableTestParamSave(bool Enable);

unsigned long GetGpsVersion();

/* Function: GetAlmanacAge
 * --------------------------
 * This function returns the age of Almanac from current time in unit of week.
 * The age of Amanac is calculated from the nearest Almanac time
 * No weekno wrap around case has been handeled yet.
 */
long GetAlmanacAge();

/* Function: GetParamAge
 * --------------------------
 * This function returns the age of parameter from current time in unit of second.
 */
long GetParamAge();

/* Function: GetFreqOffsetQuality
 * --------------------------
 * This function returns the quality of frequent offset calculation
 * return value:
 * 0 -- quality not available
 * 1 -- quality excellent (exact match)
 * 2 -- quality good (confidence in interpolation)
 * 3 -- quality fair (less confidence in interpolation/extrapolation)
 * 4 -- quality bad  (no confidence in interpolation/extrapolation)
 */
long GetFreqOffsetQuality(long tempurature);

/* Function: GetFWSStatus
 * --------------------------
 * This function returns a boolean value TRUE if GPS is currently in fast warm start mode, 
 * FALSE if GPS isn't in fast warm start mode or API function call failure
 */
bool GetFWSStatus();

/* Function: EnableFastWarmStart
 * --------------------------
 * This function enables or disables fase warm start function
 */
bool EnableFastWarmStart(bool Enable);

/* Function: EnableEnhancedColdStart
 * --------------------------
 * This function enables or disables enhanced cold start function
 */
bool EnableEnhancedColdStart(bool Enable);

/* Function: EnableEnhancedNormalStart
 * --------------------------
 * This function enables or disables enhanced warm hot start function
 */
bool EnableEnhancedNormalStart(bool Enable);

#ifdef __cplusplus
}
#endif

#endif // _GPSAPI_H_
